<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Using usage.Options</title>
  </head>

  <body>
    <h1>Using usage.Options</h1>

    <h2>Introduction</h2>

    <p>There is frequently a need for programs to parse a UNIX-like
    command line program: options preceded by <code>-</code> or
    <code>--</code>, sometimes followed by a parameter, followed by
    a list of arguments. The <code
    class="API">twisted.python.usage</code> provides a class,
    <code>Options</code>, to facilitate such parsing.</p>

    <p>While Python has the <code>getopt</code> module for doing
    this, it provides a very low level of abstraction for options.
    Twisted has a higher level of abstraction, in the class <code
    class="API">twisted.python.usage.Options</code>. It uses
    Python's reflection facilities to provide an easy to use yet
    flexible interface to the command line. While most command line
    processors either force the application writer to write her own
    loops, or have arbitrary limitations on the command line (the
    most common one being not being able to have more then one
    instance of a specific option, thus rendering the idiom
    <code class="shell">program -v -v -v</code> impossible), Twisted allows the
    programmer to decide how much control she wants.</p>

    <p>The <code>Options</code> class is used by subclassing. Since
    a lot of time it will be used in the <code
    class="API">twisted.tap</code> package, where the local
    conventions require the specific options parsing class to also
    be called <code>Options</code>, it is usually imported with</p>
<pre class="python">
from twisted.python import usage
</pre>

    <h2>Boolean Options</h2>

    <p>For simple boolean options, define the attribute
    <code>optFlags</code> like this:</p>
<pre class="python">
class Options(usage.Options):

    optFlags = [["fast", "f", "Act quickly"], ["safe", "s", "Act safely"]]
</pre>
    <p><code>optFlags</code> should be a list of 3-lists. The first element
    is the long name, and will be used on the command line as
    <code>--fast</code>. The second one is the short name, and will be used
    on the command line as <code>-f</code>. The last element is a
    description of the flag and will be used to generate the usage
    information text.  The long name also determines the name of the key
    that will be set on the Options instance. Its value will be 1 if the
    option was seen, 0 otherwise. Here is an example for usage:</p>
<pre class="python">
class Options(usage.Options):

    optFlags = [
        ["fast", "f", "Act quickly"],
        ["good", "g", "Act well"],
        ["cheap", "c", "Act cheaply"]
    ]

command_line = ["-g", "--fast"]

options = Options()
try:
    options.parseOptions(command_line)
except usage.UsageError, errortext:
    print '%s: %s' % (sys.argv[0], errortext)
    print '%s: Try --help for usage details.' % (sys.argv[0])
    sys.exit(1)
if options['fast']:
    print "fast",
if options['good']:
    print "good",
if options['cheap']:
    print "cheap",
print
</pre>

    <p>The above will print <code>fast good</code>.</p>

    <p>Note here that Options fully supports the mapping interface. You can
    access it mostly just like you can access any other dict. Options are stored
    as mapping items in the Options instance: parameters as 'paramname': 'value'
    and flags as 'flagname': 1 or 0.</p>

    <h3>Inheritance, Or: How I Learned to Stop Worrying and Love
    the Superclass</h3>

    <p>Sometimes there is a need for several option processors with
    a unifying core. Perhaps you want all your commands to
    understand <code>-q</code>/<code>--quiet</code> means to be
    quiet, or something similar. On the face of it, this looks
    impossible: in Python, the subclass's <code>optFlags</code>
    would shadow the superclass's. However,
    <code>usage.Options</code> uses special reflection code to get
    all of the <code>optFlags</code> defined in the hierarchy. So
    the following:</p>
<pre class="python">
class BaseOptions(usage.Options):

    optFlags = [["quiet", "q", None]]

class SpecificOptions(BaseOptions):

    optFlags = [
        ["fast", "f", None], ["good", "g", None], ["cheap", "c", None]
    ]
</pre>
    <p>Is the same as: </p>
<pre class="python">
class SpecificOptions(BaseOptions):

    optFlags = [
        ["quiet", "q", "Silence output"],
        ["fast", "f", "Run quickly"],
        ["good", "g", "Don't validate input"],
        ["cheap", "c", "Use cheap resources"]
    ]
</pre>

    <h2>Parameters</h2>

    <p>Parameters are specified using the attribute
    <code>optParameters</code>. They <em>must</em> be given a
    default. If you want to make sure you got the parameter from
    the command line, give a non-string default. Since the command
    line only has strings, this is completely reliable.</p>

    <p>Here is an example:</p>
<pre class="python">
from twisted.python import usage

class Options(usage.Options):

    optFlags = [
        ["fast", "f", "Run quickly"],
        ["good", "g", "Don't validate input"],
        ["cheap", "c", "Use cheap resources"]
    ]
    optParameters = [["user", "u", None, "The user name"]]

config = Options()
try:
    config.parseOptions() # When given no argument, parses sys.argv[1:]
except usage.UsageError, errortext:
    print '%s: %s' % (sys.argv[0], errortext)
    print '%s: Try --help for usage details.' % (sys.argv[0])
    sys.exit(1)

if config['user'] is not None:
    print "Hello", config['user']
print "So, you want it:"

if config['fast']:
    print "fast",
if config['good']:
    print "good",
if config['cheap']:
    print "cheap",
print
</pre>

    <p>Like <code>optFlags</code>, <code>optParameters</code> works
    smoothly with inheritance.</p>

    <h2>Option Subcommands</h2>

    <p>It is useful, on occassion, to group a set of options together based
    on the logical <q>action</q> to which they belong.  For this, the
    <code>usage.Options</code> class allows you to define a set of
    <q>subcommands</q>, each of which can provide its own
    <code>usage.Options</code> instance to handle its particular
    options.</p>

    <p>Here is an example for an Options class that might parse
    options like those the cvs program takes</p>
<pre class="python">
from twisted.python import usage

class ImportOptions(usage.Options):
    optParameters = [
        ['module', 'm', None, None], ['vendor', 'v', None, None],
        ['release', 'r', None]
    ]

class CheckoutOptions(usage.Options):
    optParameters = [['module', 'm', None, None], ['tag', 'r', None, None]]

class Options(usage.Options):
    subCommands = [['import', None, ImportOptions, "Do an Import"],
                   ['checkout', None, CheckoutOptions, "Do a Checkout"]]

    optParameters = [
        ['compression', 'z', 0, 'Use compression'],
        ['repository', 'r', None, 'Specify an alternate repository']
    ]

config = Options(); config.parseOptions()
if config.subCommand == 'import':
    doImport(config.subOptions)
elif config.subCommand == 'checkout':
    doCheckout(config.subOptions)
</pre>

    <p>The <code>subCommands</code> attribute of <code>Options</code>
    directs the parser to the two other <code>Options</code> subclasses
    when the strings <code>"import"</code> or <code>"checkout"</code> are
    present on the command
    line.  All options after the given command string are passed to the
    specified Options subclass for further parsing.  Only one subcommand
    may be specified at a time.  After parsing has completed, the Options
    instance has two new attributes - <code>subCommand</code> and <code>
    subOptions</code> - which hold the command string and the Options
    instance used to parse the remaining options.</p>

    <h2>Generic Code For Options</h2>

    <p>Sometimes, just setting an attribute on the basis of the
    options is not flexible enough. In those cases, Twisted does
    not even attempt to provide abstractions such as <q>counts</q> or
    <q>lists</q>, but rathers lets you call your own method, which will
    be called whenever the option is encountered.</p>

    <p>Here is an example of counting verbosity</p>
<pre class="python">
from twisted.python import usage

class Options(usage.Options):

    def __init__(self):
        usage.Options.__init__(self)
        self['verbosity'] = 0 # default

    def opt_verbose(self):
        self['verbosity'] = self['verbosity']+1

    def opt_quiet(self):
        self['verbosity'] = self['verbosity']-1

    opt_v = opt_verbose
    opt_q = opt_quiet
</pre>

    <p>Command lines that look like
    <code class="shell">command -v -v -v -v</code> will
    increase verbosity to 4, while
    <code class="shell">command -q -q -q</code> will decrease
    verbosity to -3.
    </p>

    <p>The <code class="API" base="twisted.python">usage.Options</code>
    class knows that these are
    parameter-less options, since the methods do not receive an
    argument. Here is an example for a method with a parameter:</p>

<pre class="python">
from twisted.python import usage

class Options(usage.Options):

    def __init__(self):
        usage.Options.__init__(self)
        self['symbols'] = []

    def opt_define(self, symbol):
        self['symbols'].append(symbol)

    opt_D = opt_define
</pre>

    <p>This example is useful for the common idiom of having
    <code>command -DFOO -DBAR</code> to define symbols.</p>

    <h2>Parsing Arguments</h2>

    <p><code>usage.Options</code> does not stop helping when the
    last parameter is gone. All the other arguments are sent into a
    function which should deal with them. Here is an example for a
    <code>cmp</code> like command.</p>
<pre class="python">
from twisted.python import usage

class Options(usage.Options):

    optParameters = [["max_differences", "d", 1, None]]

    def parseArgs(self, origin, changed):
        self['origin'] = origin
        self['changed'] = changed
</pre>

    <p>The command should look like <code>command origin
    changed</code>.</p>

    <p>If you want to have a variable number of left-over
    arguments, just use <code>def parseArgs(self, *args):</code>.
    This is useful for commands like the UNIX
    <code>cat(1)</code>.</p>

    <h2>Post Processing</h2>

    <p>Sometimes, you want to perform post processing of options to
    patch up inconsistencies, and the like. Here is an example:</p>
<pre class="python">
from twisted.python import usage

class Options(usage.Options):

    optFlags = [
        ["fast", "f", "Run quickly"],
        ["good", "g", "Don't validate input"],
        ["cheap", "c", "Use cheap resources"]
    ]

    def postOptions(self):
        if self['fast'] and self['good'] and self['cheap']:
            raise usage.UsageError, "can't have it all, brother"
</pre>

    <h2>Type enforcement</h2>

    <p>By default, all options are handled as strings. You may want to
    enforce the type of your option in some specific case, the classic example
    being port number. Any callable can be specified in the fifth row of
    <code>optParameters</code> and will be called with the string value passed
    in parameter.
    </p>

<pre class="python">
from twisted.python import usage

class Options(usage.Options):
    optParameters = [["shiny_integer", "s", 1, None, int]]
    optParameters = [["dummy_float", "d", 3.14159, None, float]]
</pre>

    <p>Note that default values are not coerced, so you should either declare
    it with the good type (as above) or handle it when you use your
    options.</p>

    <p>The coerce function may have a coerceDoc attribute, the content of which
    will be printed after the documentation of the option. It's particularly
    useful for reusing the function at multiple places.</p>

<pre class="python">
def oneTwoThree(val):
    val = int(val)
    if val not in range(1, 4):
        raise ValueError("Not in range")
    return val
oneTwoThree.coerceDoc = "Must be 1, 2 or 3."

from twisted.python import usage

class Options(usage.Options):
    optParameters = [["one_choice", "o", 1, None, oneTwoThree]]
</pre>

<p>This example code will print the following help when added to your program:
</p>

<pre class="shell">
$ <em>python myprogram.py --help</em>
Usage: myprogram [options] 
Options:
  -o, --one_choice=           [default: 0]. Must be 1, 2 or 3.
</pre>
  </body>
</html>

